<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">

<!--

[Note to FAQ maintainer - this file is kept under source control
in CVS in file doc/AAFProjectFAQ.html. Please commit your changes there
and then upload a copy to the web site. ]

-->

<HTML>
<HEAD>
<meta http-equiv="Content-Type"
      content="text/html; charset=ISO-8859-1">
<TITLE>AAF Project FAQ</TITLE>
<style type="text/css">
<!--
p {  font-family: Verdana, Arial, Helvetica, sans-serif}
-->
</style></HEAD>
<BODY bgcolor="#FFFFFF">
<!-- #BeginLibraryItem "/Library/topBanner.lbi" -->  
<table width="633" cellpadding="0" cellspacing="0">
  <tr> 
    <td width="445"><img src="http://aaf.sourceforge.net/aafDSLogo.gif" width="445" height="88" alt="AAF Developer Suppport Logo"></td>
    <td width="188"> 
      <script language="JavaScript1.1" type="text/javascript">
      <!-- protect from older browsers
      drawBannerAd();
     //protect from older browsers --> 
     </script>
    </td>
  </tr>
  <tr> 
    <td colspan="2">&nbsp;</td>
  </tr>
</table>
<!-- #EndLibraryItem -->

Originally prepared by Tim Bingham, May 2001. Acknowledgement due to
Josh Goldman who prepared the description of the directories, to
Alexey Kharkevich who provided the description of the Unix makefile
targets, Oliver Morgan who pointed out the make -&gt; Anti-Virus
workaround and to Tom Ransdell and Jeff Bedell who helped with
numerous questions. Current maintainer is <a
href="mailto:support@aafassociation.org">Simon Carter</a>.

<!--

[Note to FAQ maintainer - feel free to merge or otherwise edit this
material.]

[Note to FAQ maintainer - I removed any reference to who asked the
questions.]

[Note to FAQ maintainer - apologies that this isn't better
organized. I tried to put related questions together but with limited
time I concentrated more on filling in the answers than in
organizing.]
 
[Note to FAQ maintainer - Keep all HREF from here global e.g. starting
with http:// so that this document will still work when detatched from
the AAF support website]

--> 

<HR>
<P> How do I get started with the AAF project at SourceForge ?</P>

SourceForge is at<a href="http://sourceforge.net/">
http://sourceforge.net/</a> The SourceForge Project Info page for AAF
is <a href="http://sourceforge.net/projects/aaf/">
http://sourceforge.net/projects/aaf/</a> and the Developer Support
Webpages are at <a
href="http://aaf.sourceforge.net">http://aaf.sourceforge.net</a>

<P> How do I obtain and build the AAF SDK ?</P>

The following notes describe "Anonymous CVS Access" to the AAF source
code. Such access is read only. For read/write access please see <a
href="#howDev">How do I become an AAF developer ?</a>. This note
describes how to build the reference implementation only. Some of the
AAF source files are automatically generated, the process described
here uses pre-generated versions of those source files that have been
checked into CVS. See <a href="#regenSrc">How do I regenerate the
generated source files ?</a> regenerating the generated source files.

<P> How do I obtain and build the AAF SDK on Windows NT/Windows 2000 ?</p>

Using the WinCvs client (available from <a
href="http://www.wincvs.org/">http://www.wincvs.org</a>)

<br>
Admin -&gt; Preferences ... -&gt; Enter the CVSROOT -&gt;<font color="#FF0000"> 
  :pserver:anonymous@aaf.cvs.sourceforge.net:/cvsroot/aaf</font><br>
  Admin -&gt; Preferences ... -&gt; Authentication -&gt; "passwd" file on the 
  cvs server<br>
  Admin -&gt; Login ... -&gt; <font color="#FF0000">&lt;no password - just click 
  OK&gt;<br>
  </font>Create -&gt; Checkout module -&gt; Enter the module name and path on 
  the server -&gt; <font color="#FF0000">AAFWinSDK</font>

<br>
Open AAF/AAFWinSDK/AAFWinSDK.dsw with Visual Studio,<br> click on the
  FileView tab in the workspace view then right click on "Everything
  files" and select "Build".

<P> How do I obtain and build the AAF SDK on Linux ?</p>

  $ export CVSROOT=:pserver:anonymous@aaf.cvs.sourceforge.net:/cvsroot/aaf<br>
  $ cvs login (Logging in to anonymous@aaf.cvs.sourceforge.net) CVS password: 
  <font color="#FF0000">&lt;no password - just hit return&gt;</font><br>
  $ cvs checkout AAFLinuxSDK ...<br>
  $ cd AAF<br>
  $ make ...<br>
  $

<P> How do I obtain and build the AAF SDK on Macintosh ?</p>

<!--

[Note to FAQ maintainer, this section should be updated to describe
use of the MacCVS Pro client, the use of which is suggested elsewhere]

-->

<br>

Use the MacCvsPro client (available from <a href="http://www.maccvs.org">maccvs.org</a>)<br>
Refer to the AAF web page <a href="http://aaf.sourceforge.net/downMacOS.html">'Download 
MacOS'</a> 

<hr>

<P>OK, I've built the thing, what do I do now ?</P>

First, try running the module test program.<br> This test is self
validating if you see the following output then you probably have a
correct build.<br> Tests Run: 119 Passed: 119 Failed: 0 Not
Implemented: 0 Partial Success: 0The module test program is ...<br>
Windows COMMODAAF.EXE<br> Macintosh COMMODAAF (PPC)<br> Linux
ComModAAF Next, try running the example programs.<br> Examine the
source code and project settings (GNUmakefile) for the examples.<br>
This will show you how to get started implementing AAF in your own
applications.

<P> <a name="howDev">How do I become an AAF developer ?</a></P>

Please contact <a href="mailto:bgilmer@users.sourceforge.net">Brad Gilmer</a> 
or <a href="mailto:terabrit@users.sourceforge.net">Oliver Morgan</a> 

<P> OK, I'm a developer. How do I obtain and build the AAF SDK ?</P>

<p>How do I make checkins ?</P>

<p>What's ssh ?</p>

SSH stands for <i>Secure SHell</i>. see this<a
href="http://www.cert.org/security-improvement/implementations/i062_01.html">
CERT paper</a><br> Note that you can't easily use the CVS workspace or
sandbox you checked out anonymously with your developer account
because all the CVS directories embedded in your checked out workspace
contain a <b>Root</b> file specifing the original checkout
parameters.<br> Although this can be overriden by explicitly forcing a
new access method with each command<font face="Courier New, Courier,
mono" size="+1"><br> cvs -d :ext:<font color="#FF0000">&lt;developer
name&gt;</font>@aaf.cvs.sourceforge.net:/cvsroot/aaf</font> ... <br>
It's much more sanitary to do a new clean checkout.<br> Refer to the
AAF web pages <a href="http://aaf.sourceforge.net/sshWin32.html">Using
CVS/ssh on Windows</a> or <a
href="http://aaf.sourceforge.net/sshMacOS.html">Using CVS/ssh on
MacOS</a><br> <br>

<p>How do I use CVS/ssh on Linux ? </p>

<br>
$ export CVSROOT=:ext:<font color="#FF0000">&lt;developer name&gt;</font>@aaf.cvs.sourceforge.net:/cvsroot/aaf 
<br>
$ export CVS_RSH=ssh ... <br>
$ cvs checkout -rRC1 AAFLinuxSDK<br>
<font color="#FF0000">&lt;developer name&gt;</font>@aaf.cvs.sourceforge.net's 
password: <font color="#FF0000">&lt;enter your password&gt;<br>
</font>cvs server: Updating AAF ...<br>
<br>
$ cvs commit -m"Add new defrobnicate() member." frobber.cpp<br>
<font color="#FF0000">&lt;developer name&gt;</font>@aaf.cvs.sourceforge.net's 
password: <font color="#FF0000">&lt;enter your password&gt;<br>
</font>...<br>
$ . 

<p>Help - Redhat Linux 6.1 doesn't come with ssh pre-installed !</p>

Unlike Redhat 7.x. you have to install ssh from an RPM. Note that SSH
2.0 can be used despite notes to the contrary on SourceForge that
state only SSH 1.5 is supported.

<p>I get errors first time I use SSH access to SourceForge what's
going on ?</p>

SourceForge does not create a home directory for you until you attempt a real 
login to the server (as opposed to a CVS session) with name and password:<br>
ssh -l <font color="#FF0000">&lt;myname&gt;</font> aaf.cvs.sourceforge.net 

<p>My company's firewall is preventing me accessing sourceforge what
  do I need to do ? </p>

see tha AAF web page <a
href="http://aaf.sourceforge.net/sshFirewall.html">Firewalls and
SSH</a>

<HR>
<P> What kinds of changes are allowed ?</P>

You may add new interfaces. 

<P> What kinds of change are NOT allowed ?</P>

You may not change existing interfaces. Here <b>interface</b> means
interface in the COM sense. e.g. IAAFEssenceAccess as defined in
AAF.idl You may not change existing interfaces as this would break
binary compatibility. Binary compatibility is the ability of an
existing explication (perhaps one developed with an older
<b>aafdll</b>) to work correctly with a newer <b>aafdll</b>.

In the newer <b>aafdll</b> interfaces must not have changed otherwise
code in the old application will not work correctly. Newer
applications can take advantage of new interfaces in in the new
<b>aafdll</b> that will simply be ignored by older applications.

<!--

[Note to FAQ maintainer - this is _very_ important. I'm concerned
about recent discussions to _change_ the EssenceAccess
interface. Doing so would be incorrect.]

-->

Another advantage of maintaining binary compatibility is that bugs can
be fixed "at run time". That is, if an older <b>aafdll</b> contains
bugs, a newer one with the bugs fixed can only be substituted safely
provided that no interfaces have been changed.

<P> How do I add a new interface ?</P>

You'll need to speak to "dodo" :-)

<!--

[TBS - but seriously]

--> 
<P> How are changes approved ?</P>

The AAF engineering committee is responsible for defining this process.

<!--

[TBS - more detail, or a web link, needed on exactly what the process is.]

 --> 

<P> What are the rules for interface design. I notice that there are
  no parameters of built-in type, such as "int" ?</P>

<ul>

  <li>no parameters of built-in type such as "int" since the sizes of
    the builtin type vary (across platforms, between compiler on the
    same platform and even for the same compiler with different
    options).</li>

  <li> no parameters of type enum (same reasons as above)</li>

  <li>no hidden pointers (e.g. as a struct member)

<!--
[reason - TBS]
[others - TBS]
 --> 

  </li>
</ul>

<HR>

<P> What platforms are supported ?</P>

As of RC1 (the initial sources made available on SourceForge April 17,
  2001) the supported platforms are (in no particular order)

<ul>

  <li>Windows NT Version 4.0 Intel Visual C++ Version 6.0 (Service Pack 2)</li>

  <li>Windows 2000 Professional Intel Visual C++ Version 6.0 (Service
  Pack 2)</li>

  <li>Macintosh Mac OS 8.6 PPC Code Warrior 5 (IDE 4.0.4)</li>
  <li>Macintosh Mac OS 9.2 PPC Code Warrior 6 (IDE 4.1)</li>
  <li>Red Hat Linux 6.0 Intel gcc <!--[version TBS] --></li>
  <li>Red Hat Linux 6.1 Intel gcc 2.95.2</li>
  <li>Red Hat Linux 7.1 Intel gcc 2.96 [some functions NYI as of 5/25/01]</li>
  <li>SGI Irix 6.5 MIPS gcc 2.95.2</li>
  <li>SGI Irix 6.5 MIPS MIPSpro 7.2.1 (CC -n32)</li>
</ul>

<br>The above platforms are those on which the AAF project is known to
  build and run correctly.

<p> Will the SDK compile with gcc 3.0 ? </p>

No yet, Note gcc versions prior to 3.0 don't have support for wide
streams (wostreams). I discovered this problem in gcc version 2.96.
no-one has yet made any effort to fix this problem.
<br>
gcc 2.96 also has problems with basic_string&lt;wchar_t&gt;::c_str().  3.0
fixes that as well.  (It looks like std lib string support was
completely redone in 3.0)

<P> What's the earliest MacOS that the SDK will work on ?</P>

MacOS 8.6 is the earliest on which we've tested RC1. 

<P> What about Macintosh OSX ?</P>

One dependency here is on a Carbonized version of the <b>Microsoft Structured 
Storage</b> system extension. This is not yet available from Microsoft. 

<P> Does AAF build with CodeWarrior 6.0 ?</P>

Not quite there are syill a couple of outstanding Link problems 31/7/01. 

<P> <a name="win9598MEsupport">What about Windows 95, Windows 98 and
  Windows ME ?</a></P>

For brevity, let's refer collectively to Windows 95, Windows 98 and Windows ME 
as consumer versions of Windows. <br>
We have not tested building and running AAF on consumer versions Windows as we 
have on the "supported" platforms. However AAF does build and run on consumer 
versions of Windows after some minor modifications to the Visual C++ projects. 
<br>

To be able to build and run AAF on a consumer version of Windows you
must change the C/C++ settings in the following projects ...<br>

<br>
./AAFWinSDK/ref-impl/aaflib/AAFLIB.dsp<br>
./AAFWinSDK/ref-impl/Om/Om.dsp<br>
./AAFWinSDK/DevUtils/Dump/Dump.dsp <br>
<br>

Go to Settings -&gt; C/C++ -&gt; General -&gt; Preprocessor
Definitions and add -DNO_W32_WFOPEN (make sure "Settings for:" says
"All Configurations")<br> If you wish to create a single <b>aafdll</b>
that runs on consumer versions of Windows and on Windows Nt/2000, then
different changes would be required.

<P> What other tools will I need besides a C++ compiler ?</P>
GNU make version 3.77<br>
Perl version 5.002

For "Anonymous CVS Access" to the AAF project on SourceForge you need
a CVS client. We suggest the following clients Operating System CVS
Client Available from Windows NT/Windows 2000 WinCvs
http://www.wincvs.org/ Macintosh Mac OS 8.6/9.0 MacCVS Pro
http://www.maccvs.org/ Note that there are several other Macintosh CVS
clients with similar sounding names. On Linux we suggest the the
cvs(1) command.  For brevity, let's refer collectively to Windows 95,
Windows 98 and Windows ME as consumer versions of Windows. We have not
tested building and running AAF on consumer versions Windows as we
have the above platforms. However AAF does build and run on consumer
versions of Windows after some minor source code modifications.  To be
able to build and run AAF on a consumer version of Windows you must
make the following changes. In the following files change the
implementation of wfopen() so that the non-Windows code is compiled
even though you are compiling on Windows 95 or 98. This is necessary
because, although _wfopen() exists and is implemented in the W32 API
on Windows 95 and 98, it always fails. ./ref-impl/aaflib/aaflib.cpp
./ref-impl/src/OM/OMUtilities.cpp If you want to use the low-level
file dumper on Windows 95 or 98 you'll need to make a similar change
in the following file ... ./DevUtils/Dump/dump.cpp If you wish to
create a single <b>aafdll</b> that runs on consumer versions of
Windows and on Windows NT/2000, different changes would be required.

<P> What about Red Hat Linux version 7.1 ?</P>

As of RC1 (the initial sources made available on SourceForge April 17,
2001) AAF does not build on Red Hat Linux version 7.1. [Note to FAQ
maintainer, I've since ported AAF to Red Hat Linux version 7.1 and
checked the changes into SourceForge.  I have notes on what I
did. There are still a few warnings. I didn't bother getting the
AAF/OMF converter to compile since there's no version of OMF for Linux
yet.  Also remaining to be done are implementations of the functions
AafPos2AnsiPos() and AnsiPos2AafPos() in
ref-impl/plugins/CAAFEssenceFileStream.cpp]

<P>When I open up AAFWinSDK.dsw I get a message "Unable to connect to
  source code control project AAFStandardCodecs". How can I get rid of
  this ?</P>

What's happening is that you have Visual Source Safe (Microsoft's
source control product) installed as well as Visual Studio, Visual
Source Safe is insisting on looking for a source control project even
though none exists.<BR> You can get rid of the message temporarily
(the setting is saved in AAFWinSDK.opt) by answering "no" to the
question "Do you wish to attempt this connection in future sessions ?"
To get rid of the message permanently, change the value of the
registry key HKEY_CURRENT_USER\Software\Microsoft\DevStudio\6.0\Source
Control\Disabled from 0 to 1. This part of the registry contains all
the settings from the Visual Studio -&gt; Tools -&gt; Options
... -&gt; Source Contol dialog. Unfortunately it seems that there's no
UI checkbox to disable Visual Studio/Visual Source Safe
integration. For more details see <a
href="http://support.microsoft.com/support/kb/articles/Q236/3/99.ASP">
http://support.microsoft.com/support/kb/articles/Q236/3/99.ASP</A>

<P> Where can I find out more about CVS ?</P>

There's information to help you get started on SourceForge<br>

<img src="http://aaf.sourceforge.net/fogelBook.gif" width="111" height="140" align="right"
alt="Fogel CVS book">

One book CVS I have found useful is Karl Franz Fogel, "OpenSource
Development with CVS", November 1999, The Coriolis Group, ISBN:
1576104907. Most of this is available online at <a
href="http://cvsbook.red-bean.com/">http://cvsbook.red-bean.com/</a><br>
<br> There's a catalog of CVS documentation at <a
href="http://www.cvshome.org/docs/index.html">http://www.cvshome.org/docs/</a>
I've found the PDF version of the "the Cederqvist" - the "official"
CVS manual by Per Cederqvist most useful. There's also the book by Per
Cederqvist "Version Management With CVS", December 2000,
iUniverse.com, ISBN: 0595149219. I'm not sure how this differs from
the stuff by Cederqvist that's available online.

<P> My line endings are messed up. What's going on ?</P>

CVS rules for text files. - files are stored in the CVS repository
with Unix line endings. - the CVS client converts the CVS repository
line endings to/from the endings appropriate to your platform when you
commit/checkout the file. - the conversions performed by the CVS
client are dumb in that they expect the input file to have the correct
line endings for their platform i.e. they convert a valid file rather
than fix up an invalid one. So if the file starts out with the wrong
line endings for the CVS client that is used to check it in, then the
file will get mangled. e.g. checking in a file with Windows line
endings using a Macintosh CVS client will probably transform "\r\n" to
"\n\n", if you check this file out you'll see an extra blank line
between every existing line. Adding a text file - before you add a
text file make sure the file has the line endings appropriate to the
platform from which you are adding the file. Fixing a file - checkout
the file, convert the line ending to those appropriate to your
platform (remembering that they may have been mangled) and then check
it back in. CVS will do the right thing from then on. Line ending
conventions Unix \n Windows \r \n Macintosh \r

<P>My binary file is messed up. What's going on ?</P>

Chances are the file isn't correctly tagged as binary in CVS, check
the CVS/Entries file for the current directory files that were
orginally added as binary have the -kb flag against them.

<p>I get the error message &quot;Connection refused&quot; from
Sourceforge ?</p>

Check you have a <b>CVS_RSH</b> environment variable correctly set to
  <b>SSH</b>

<p>How can I add a MacOS alias (symbolic link or shortcut) to CVS ?<p>

Use MacCVSpro, it seems to be smart enough to figure out the special
type and convert it to Apple single.  <HR>

<P> What are the pieces of the AAF project ?</P>

The AAF project consists of the following pieces

<ul>

<li> Tools needed to generate some of the AAF source files together
with input files for those tools. Pre-generated files are included
since they don't always need to be regenerated.</li>

<li> The complete source code for the AAF reference
implementation</li>

<li>Other components upon which the AAF project
depends

<ul>

<li>OMF header files and libraries</li>

<li>Microsoft Structured Storage - On Macintosh this is part of Mac
OLE (header files and libraries are included in the AAF project) - On
Windows the header files and libraries are part of the Microsoft
supplied platform SDK (not included in the AAF project) - On other
platforms the Microsoft Structured Storage reference implementation is
used (header files and libraries for Linux (Intel) and SGI Irix are
included in the AAF project. For other platforms the source code for
the Structured Storage reference implementation can be licensed from
Microsoft.)</li>

</ul>

<li>Module tests, one per AAF class</li>
<li>Test programs</li>
<li>Example programs</li>
<li>Utility programs</li>

</ul>

<P> What are the steps in the process of building an AAF SDK from the
  AAF project ?</P>

<ul>
  <li>generate files 
    <ul>
      <li>build dodo tool </li>
      <li>run dodo tool to generate files</li>
    </ul>
  <li>build AAF reference implementation </li>
  <li>create SDK</li>
  <li>build tests using SDK</li>
  <li>build examples using SDK</li>
</ul>

These are <b>all</b> of the steps. Step 1 isn't necessary unless
you've changed the dodo inputs files. To avoid everyone having to do
step 1 the generated files are checked in to CVS. Note that
regenerating the source files isn't done (by default) by the projects
or makefile.

<!--
TBS - more detail on each of the steps
--> 


<P> <a name="regenSrc">How do I regenerate the generated source files ?</a></P>

To regenerate the generated files you need to "cd dodo; make". There
is one caveat which only applies if you want to regenerate the
generated source files, for example, if you are adding a new interface
to the AAF API. Up to date generated source files as well as the files
from which they are derived are checked into CVS. However, when you
download them from CVS, "make" may think that the generated files need
to be regenerated (since the files get modification times
corresponding to the time that the working copy is created and not
when the file was checked in to CVS).

<P> Why does "cvs checkout" take so long ?</P>

If you are using a slow (e.g. 56K or ISDN) link consider setting the
CVS compression option<b> cvs -z3</b> (tune the compression level for
best results), compression is tradeoff between the horsepower
available at each end of the link compared to the thickness of the
pipe.<br> <br> Make sure you are checking out the platform specific
module such as <b>AAFWinSDK</b> rather than the default <b>AAF</b>
module which contains the entire source tree.<br> <br> For the time
being if you just want the pre-built SDK for you platform you'll also
get the source code needed to build it. <br> After the first checkout
a <b>cvs update -d</b> command will be considerably faster since it
only needs to retrieve the changed files and new directories.<br> <br>
Modules still need to be defined for - pre-built SDKs on Windows,
Macintosh and Unix (these will also be made available as "released
files").<br> These modules would be checked out by those wishing only
to <i>use</i> the AAF SDK. <br> These users could also be satisfied by
pre-built SDKs in the form of "released file packages". - everything
needed to be a reference implementation developer (i.e. make a change,
such as a bug fix to some existing code.)<br> These modules would be
checked out by those wishing to enhance the AAF SDK and by those who
wish to port the SDK to a new platform. - everything needed to add new
interfaces to AAF. This would include the dodo tool. This would be
done by those wishing to extend the set of interfaces supported by
AAF.

<P> I just want to use the AAF SDK, why do I have to build it first ?</P>

Because CVS modules and/or "released file packages" are not yet available. 

<P> What is dodo ?</P>

dodo is a tool used to generate some of the AAF source files. It
allows multiple output files, that must be kept in sync with each
other, to be generated from a single source. If you need to make a
change that has an impact in more than one place you need only change
the dodo input file. The original idea for dodo was that all the files
it generated would eventually be maintained by hand at which point
dodo could be made extinct. Hence the name "dodo". However, dodo was
useful enough that it became used for code that is always generated,
meaning that dodo must be kept alive.

<P>Why does making dodo on Win2K fail with UNAME := $(shell uname) ?</P>

The above is a GNUmake specific construct (It means run the uname
command in the shell and put the output in the make symbol UNAME). You
need GNUmake to use this makefile. GNUmake should be listed as one of
the prerequisites for building Dodo on Windows.  <br>

Since the generated files are checked in to SourceForge you don't need to run
dodo unless you are adding a new interface (you aren't allowed to change
existing interfaces) or changing the generated code (in a compatible way).

<!--

[TBS - more detail on dodo input and output files.]

--> 

<HR>

<P> I get the following error from CodeWarrior when building from
  scratch. Error : ### Error: Out of memory ### Link Error : Link
  failed. </p>

I've seen this error too but could never track it down. It seems only
to happen when compiling and linking from scratch and seems also to be
related to the amount of memory allocated to CodeWarrior (oddly enough
allocating more memory seemed to cause it more often). The error goes
away if you try again.

<P> I get an out of memory error from CodeWarrior 6 when building
<b>ModuleTests/CAAFDictionaryTest.cpp</b></p>

This test does #include files like AAFStoredObjectIDs.h,
AAFTypeDefUIDs.h and AAFClassDefUIDs.h which do a lot of macro
expansion via AAFMetaDictionary.h it seems to need more than 128MB for
this !

<HR>

<P> When I build on Macintosh I get warnings. What's the house style
  guide say on the acceptability of Warnings ?</P>

These warnings should be cleaned up, most are unused argument errors
but some could indicate more serious problems. The intent is that
warnings are not acceptable and that the compiler should be set to the
highest level of warnings as is practicable, if possible the compiler
should be set to treat all warnings as errors. For gcc this means
"-Wall -Werror".

<HR>

<P> When I build on Irix I get the following error. What's going on?</P>

"../../include/OM/OMContainerElement.h", line 36: error(1020):
identifier "typename" is undefined<br>

You are using the wrong compiler (probably "CC -o32") this compiler is so old 
it doesn't recognize the "typename" keyword. Use "CC -n32" or gcc instead. 

<HR>

<P> On Linux the default make at the top level doesn't descend all the
  branches, it only seems to build in ref-impl. Is this correct ?</P>

Yes, this is correct for the default make file target. The default
target (make with no arguments) is the reference implementation
libraries. There are a number of other targets in the makefile. Here's
an overview of the makefile targets.  <br>

<!--

[Note to FAQ maintainer, I didn't have time to edit this for consistency.]

-->

To build AAF reference implementation libraries type: make<br> Now you
have to install libraries and header files to create AAF SDK to use
with your applications:<br>

<font face="Courier New, Courier, mono">make install</font> or <font face="Courier New, Courier, mono">make 
install AAFSDK=/home/user/New_AAF_SDK</font><br>
You can do 'make install' without doing 'make' first. If 'make install' cannot 
find libraries to install it will build them.<br>
With SDK created you now can build applications. To build applications distributed 
with the AAF SDK you can do:<br>
<font face="Courier New, Courier, mono">make test<br>
make examples<br>
make utilities<br>
make devutils </font><br>
or make everything<br>
If make cannot find installed AAF SDK it will build (if necessary) and install 
the SDK before building applications.<br>
Binaries are placed in the SDK's bin directory. Do not forget that if you use 
install directory other than default you have to specify it:<br>
<font face="Courier New, Courier, mono">make everything AAFSDK=/home/user/AAF_2001 
</font> 

<p>How about cleaning up ?</p>

<font face="Courier New, Courier, mono">make clean</font> will remove: all the 
intermediate files (like .o for), libraries (except installed SDK libraries), 
and applications (tests, examples, utilities).<br>
To remove SDK do make uninstall which removes all the installed libraries and 
header files. Again, don't forget that you may need to use: make clean AAFSDK=/usr/local/aaf 
make uninstall AAFSDK=/usr/local/aaf 

<p>What about running dodo ?</p>

Dodo is utility to generate COM interfaces. By default all the
generated files are already there and do not get touched by commands
mentioned above. If you want to remove generated files along with
compiled files do: make realclean 'make realclean' does 'make
uninstall', 'make clean' and then removes all the generated files
created by the dodo tool. Want to skip 'unistall' and 'clean'? Do: cd
dodo; make realclean With generated files missing the next try to
build the SDK ('make') will launch dodo to generate them. If you want
just generate files without building anything do: cd dodo; make

<P> When building on Linux I get errors because the directory
  "AAFi686LinuxSDK/g++/bin/debug/" does not exist. What's going on
  ?</P>

Most likely you are trying to make in the examples directory before
running <b>make install</b> at the top level to create the target
directories.


<!--

[TBS - how do I do Release vs. Debug builds on Unix/Linux]

-->

<HR>

<P> What are the major components of the AAF architecture ?</P>

<ul>

  <li>The AAF (COM) API (ref-impl/src/com-api) <!--[TBS - more detail
  needed] --></li>

  <li> The AAF Data Model Manager (ref-impl/src/impl) </li>

<!--

[TBS - more detail needed]

-->


  <li>The Object Manager (ref-impl/include/OM and ref-impl/src/OM)
<!--[TBS - more detail needed] --> </li>

</ul>

<P> What's the run time architecture ?</P>

You link your application to a small static library <b>aaflib</b>
which exports a small number of entry points, such as
AAFFileOpenExistingRead(). <br> At run time, code in <b>aaflib</b>
dynamically loads <b>aafdll</b>, the actual guts of the AAF reference
implementation, and resolves these symbols.<br> You must also link
your application to <b>aafiid</b> a static library that defines the
IIDs (Interface identifiers) for the AAF interfaces.

<P> What are the libraries called and where is their code ?</P>

The actual library files have names that vary across platforms. The
platform specific names are given in the table below. To refer to a
library in a platform independent way I've used names such as
<b>aaflib</b>, <b>aafiid</b> and <b>aafdll</b>.

<table cellspacing="6" cellpadding="6" border="0">
  <tr> 
    <td>Library</td>
    <td>Source</td>
    <td>Description</td>
    <td>&nbsp;</td>
    <td>Windows</td>
    <td>Macintosh</td>
    <td>Unix Library</td>
  </tr>
  <tr> 
    <td rowspan="2">aaflib</td>
    <td rowspan="2">ref-impl/aaflib</td>
    <td rowspan="2">static stub library</td>
    <td>Debug</td>
    <td>AAFD.LIB</td>
    <td>AAFLIB (Debug)</td>
    <td>libaaflib.a</td>
  </tr>
  <tr> 
    <td>Release</td>
    <td>AAF.LIB</td>
    <td>AAFLIB</td>
    <td>libaaflib.a</td>
  </tr>
  <tr> 
    <td rowspan="2">aafiid</td>
    <td rowspan="2">ref-impl/aafiid</td>
    <td rowspan="2">interface identifiers</td>
    <td>Debug</td>
    <td>AAFIIDD.LIB</td>
    <td>AAFIIDD.LIB</td>
    <td>libaafiid.a</td>
  </tr>
  <tr> 
    <td>Release</td>
    <td>AAFIID.LIB</td>
    <td>AAFIID.LIB</td>
    <td>libaafiid.a</td>
  </tr>
  <tr> 
    <td rowspan="2">aafdll</td>
    <td rowspan="2">ref-impl/src</td>
    <td rowspan="2">the AAF reference implementation</td>
    <td>Debug</td>
    <td>AAFCOAPI.DLL</td>
    <td>AAFCOAPI.DLL (PPC)Dbg</td>
    <td>libcom-api.so</td>
  </tr>
  <tr> 
    <td>Release</td>
    <td>AAFCOAPI.DLL</td>
    <td>AAFCOAPI.DLL (PPC)</td>
    <td>libcom-api.so</td>
  </tr>
  <tr> 
    <td rowspan="2">omf</td>
    <td rowspan="2">OMF/Include</td>
    <td rowspan="2">the OMF toolkit used by the OMF-AAF converter</td>
    <td>&nbsp;</td>
    <td>&nbsp;</td>
    <td>&nbsp;</td>
    <td>&nbsp;</td>
  </tr>
  <tr> 
    <td>&nbsp;</td>
    <td>omfToolkit.dll</td>
    <td>libOMFANSIC.a</td>
    <td>libOMFI.a</td>
  </tr>
</table>

<P> What are AAFINTP.DLL and AAFPGAPI.DLL ?</P>

AAFINTP.DLL is an example interpolator plugin and AAFPGAPI.DLL is an
example essence codec plugin (AIFC, CDCI, WAVE and JPEG codecs). The
AAFPGAPI.DLL also contains the external essence container code as well
as the essence data stream helper class. If future it would be a good
idea to move the essence data helper class into "aafdll" (inside the
AAF essence access class).

<HR>

<P> What's all that funny stuff like "@mfunc" and "@rdesc" in the
  comments of the source files in ref-impl/src/OM and
  ref-impl/include/OM ?</P>

These are special comments recognized by AutoDuck (AutoDuck is
Freeware by Eric Artzt). AutoDuck extracts the comments and produces
documentation in a variety of formats. While AutoDuck is not
particularly smart about C++ (e.g. it gets confused about overloaded
functions) the hyperlinked html output is very useful.

<p>Where can I get Autoduck from ?</p>

try <a
href="http://www.devstuff.com/utils.htm">http://www.devstuff.com/utils.htm</a>
note there are some older versions around that don't do HTML

<P> OK, where can I get the html ?</P>

Run the script ref-impl/doc/OM/makedocs.ksh. Note that this script
expects that you already have Autoduck (AFAIK only available for
Windows) and that documentation only for the Object Manager
(ref-impl/src/OM and ref-impl/include/OM) will be generated.

<HR>

<P> What do I need to port AAF to a new platform ?</P>

<ul>

<li>a C++ compiler of recent vintage. We don't insist on ISO/ANSI
since we've deliberately avoided some of the really new features. We
do however, use some of the more well establish features. gcc (g++) is
recommended.</li>

<li>an implementation of Microsoft Structured Storage for your
platform.</li>

</ul>

<!--

[TBS]

 --> 

<P> Don't I need an implementation of COM ?</P>

No. 

<P> Are you sure I don't I need an implementation of COM ?</P>

Yes, we're sure. 

<P> How is the Microsoft COM stuff distributed for Irix &amp; Linux -
  it seems to miraculously work, is there a binary lib tucked away in
  the Distribution ?</P>

No it really is a miracle :-)

<!--

[TBS - more detail needed on how we don't really use COM]

--> 

<P> OK. So what C++ features does the code use and which does it avoid ?</P>

Features we use
<ul>
<li> "bool"
<li> class templates (including "typename")
<li> static_cast&lt;&gt;, dynamic_cast&lt;&gt;, const_cast&lt;&gt;
     and reinterpret_cast&lt;&gt;
</ul>
Features we have avoided
<ul>
<li> "mutable"
<li> "namespace"
<li> standard template library
<li> class type_info, typeid operator
<li> function templates, class/function template specialization,
     class/function template partial specialization
<li> covariant virtual function return types
<li> unbound friend class/function template declarations
<li> Other - note that we do use wchar_t from &lt;stddef.h&gt; and the wcs
     functions (e.g. wcslen()) from &lt;wchar.h&gt;. Since this is a relatively
     new addition to the ISO C libraries it may raise portability issues. 
</ul>

<HR>

<P> I thought the AAF code was supposed to be portable, why does the
  code contain references to IStorage and IStream ? Aren't those
  Windows specific things ?</P>

AAF is portable, however it does depend on Microsoft Structured
Storage. IStorage and IStream are interfaces with implementations in
Microsoft Structured Storage.  Implementations of Microsoft Structured
Storage for Windows and Macintosh are available directly from
Microsoft and are included (headers and binaries) with AAF. On other
platforms it is possible to licence the source code for the Structured
Storage reference implementation from Microsoft. Header files and
binaries for Linux and Irix are included.

<P> <a name="#OMdebug"></a>Why does the Object Manager
  (ref-impl/src/OM and ref-impl/include/OM) depend on
  &lt;iostream.h&gt; ?</P>

The release build does not. The debug build does. The default
configuration for the debug build defines OM_DEBUG which enables
run-time assertion checking.  If an assertion fails information about
the failing assertion is written to "omlog" an instance of class
OMOStream. The distributed version of OMOStream is implemented using
&lt;iostream.h&gt; (only four functions in OMOStream.cpp). If you
don't have (or don't want to use) &lt;iostream.h&gt; you can either
reimplement the four functions in OMOStream.cpp or change the body of
function reportAssertionViolation() in OMAssertions.cpp to do
something different.

<HR>

<P> Why does it say "This Project Has Not Released Any Files" on
  https://sourceforge.net/projects/aaf/, I thought that all of the
  source for AAF had been released ?</P>

Here "released files" refers to the output of a project, in the form
of "file packages" or "tarballs") ready for use by others. The
SourceForge AAF project has not yet released any file packages these
will probably be in the form of pre-built AAF SDKs for various
platforms

<HR>

<P> What are the TRACE(), PRECONDITION(), POSTCONDITION() and ASSERT()
  calls in the Object Manager (ref-impl/src/OM and
  ref-impl/include/OM) ?</P>

The macros support the use of design and programming by contract. See
Bertrand Meyer, "Object-Oriented Software Construction, 2nd Edition",
March, 2000, Prentice Hall, ISBN: 0136291554

<HR>

<!--

What are the coding conventions ? 

How do I make sure my changes are portable ?

-->

<P> What are each of the directories for ?</P>

<!--

[Note to FAQ maintainer - This is not completely accurate, I didn't
have time to check and edit this.]

-->

Here's a brief guide to the AAF Source Tree, 
focusing on where to find useful bits of information. 
<h4>AAFWinSDK</h4>
Windows project files and default location for compiles and links (Windows 
  platform only)
<h4>bin</h4>
Obsolete
<h4>DevUtils</h4>
Utilities useful to AAF Developers.<br> There's only one of these,
  a low-level dumper that helps diagnose file format problems.
  <h4>doc</h4>
Currently obsolete, will have doc files
<h4>dodo</h4>

<a href="http://aaf.sourceforge.net/dodo.html">dodo</a> is a tool
  we use to generate our header files.<br> This directory contains the
  dodo input file (*.dod). The dodo input files use macros defined in
  *.mac files in the macros directory. The comments in the *.dod files
  end up in the <a
  href="http://aaf.sourceforge.net/doc/com-api/contentsf.html">API
  reference document</a>.

<h4>examples</h4>

Useful examples and some useful dump utilities meta Spreadsheet
  that defines the AAF object model, used to generate the
  AAFMetaDictionary.h file and the dictionary stored in the AAF
  file. (see ref-impl/src/impl for definitions used by the reference
  implementation for builtins)

<h4>omf</h4>
OMF toolkit headers and libraries for the OMF converter
<h4>ref-impl</h4>
Sources for the Com interfaces and the implementation code.
<h4>ref-impl/aafiid</h4>
<h4>ref-impl/aaflib</h4>
<h4>ref-impl/bld_cfg</h4>
<h4>ref-impl/include</h4>

Contains the .idl and .h files used by the implementation
  (including those exported to AAF clients). The top-level include
  directory has the include files that are not generated from .idl
  files.<br> AAFClassDefsUIDs.h defines the macros for defining the
  symbols and AUIDs for the stored classes, but does not contain the
  list of symbols and the AUIDs.  The symbols for a class ID is in the
  format kAAFClassID_&lt;class-name&gt; However, the implementation
  code uses some shortened names for these symbols and
  AAFClassDefsUIDs.h defines symbols with the longer name. In general,
  the following abbreviations are used

<table border="0" cellpadding="6" cellspacing="6">
  <tr> 
    <td>Abbreviated form</td>
    <td>Long form</td>
  </tr>
  <tr> 
    <td>Def</td>
    <td>Definition Object</td>
  </tr>
  <tr> 
    <td>IntObj</td>
    <td>InterchangeObject</td>
  </tr>
  <tr> 
    <td>ObjRef</td>
    <td>ObjectReference</td>
  </tr>
  <tr> 
    <td>Int</td>
    <td>Integer</td>
  </tr>
</table>

In addition, there are a few symbols defined for multiple spellings
  (UNIX and Unix, EdgeCode and Edgecode)<br>
  <b>AAFPropertyDefs.h</b> defines the macros for defining AUIDs for
  property ID and AAFPropertyIDs.h invokes the macros, but neither
  contains the symbol and the AUID defined for each property. The
  symbol for a property is in the format
  kAAFPropID_&lt;class-name&gt;_&lt;property-name&gt; with the added
  complication that the class-name used is the modified short name
  used in the code.

<h4>ref-impl/include/com-api</h4>
Contains the .idl files for the Com interfaces

<b>AAF.idl</b> defines the interfaces and methods and AAFTypes.idl
  defines the types ref-impl/include/om Contains the header files used
  internally by AAF data manager for the AAF object manager

<h4>ref-impl/include/ref-api</h4>

Contains the .h files generated from the .idl files and private .h
  files used by the AAF data manager

<h4>ref-impl/libjpeg</h4>
Contains jpeg source code used by the JPEG codecs with the CDCI format.
<h4>ref-impl/plugins</h4>

Contains the source code used by the plugins provided with the
  reference implementation.  These plugins are AIFC codec, JPEG codec,
  WAVE codec, Interpolator plugin, Plugin manager code

<!--

??? anything else

--> 

<h4>ref-impl/src</h4>

Contains the source code for the reference implementation

<h4>ref-impl/src/com-api</h4>

Contains the source code for the Com interfaces. The top-level
  directory contains the .cpp and .h file for each Com
  interface. <b>CAAFAIFCDescriptor.cpp</b> contains the source code
  associated with the AAFAIFCDescriptor class. In general the methods
  in the Com interfaces call methods of the same name in the
  implementation object. The .h files contain the information about
  which interfaces an implementation object supports. In general, for
  Com objects that are associated with AAF Specification classes, the
  implementation object will support the Com interface associated with
  the stored class and the Com interfaces associated with the parent
  class of the stored class.<br> This is indicated by the lines that
  start the class definition in the .h file.<br> For example, the
  AAFFiller stored class inherits from the AAFSegment class

class CAAFFiller : public IAAFFiller, public CAAFSegment

In addition, some implementation objects support additional
  interfaces.<br> For example, the implementation class associated
  with the <b>AAFMasterMob</b> class also supports the
  <b>IAAFSearchSource</b> interface.<br> This is shown by the
  following lines in the<b> CAAFMasterMob.h</b> file:

class CAAFMasterMob : public IAAFMasterMob, public IAAFSearchSource, public 
  CAAFMob

<h4>ref-impl/src/com-api/com-dll</h4>

<!--?? -->Contains the code managing loading the AAF .dll and creating Com 
  objects.

<h4>ref-impl/src/impl</h4>

Contains the .cpp and .h files that define the implementation
  objects.<br> The <b>Impl&lt;class-name&gt;.cpp</b> contains the body
  of the code.<br> The <b>Impl&lt;lclass-name&gt;.h</b> files contains
  the header and specifies the actual datatypes used by the
  implementation for builtin properties.<br> These types should match
  the ones specified in the meta directory and in the metadictionary.h
  file. The property datatypes are specified in the end of the .h file
  in under the private label.<br> The datatypes are specified in the
  underlying object manager type with the typedef name of the property
  datatype name.<br> For example,<b> ImplAAFPulldown.h</b> specifies
  the following properties and types:

OMStrongReferenceProperty&lt;ImplAAFSegment&gt; _inputSegment;<br>
  OMFixedSizeProperty&lt;aafPulldownKind_t&gt; _pulldownKind;<br>
  OMFixedSizeProperty&lt;aafPulldownDir_t&gt; _pulldownDirection;<br>
  OMFixedSizeProperty&lt;aafPhaseFrame_t&gt;_phaseFrame;

And in <b>ImpleAAFMobSlot.h</b>, the following properties are listed:
OMWideStringProperty _name;<br>
  OMFixedSizeProperty&lt;aafUInt32&gt; _trackID;<br>
  OMFixedSizeProperty&lt;aafUInt32&gt; _physicalTrackNum;<br>
  OMStrongReferenceProperty&lt;ImplAAFSegment&gt; _segment;
<h4>ref-impl/src/om</h4>
Contains the source for the AAF object manager
<!-- ReleaseNotes Contains the release notes --> 
<h4>test</h4>
Contains the test files
<h4>test/com/ComModTestAAF</h4>

Contains the module tests. This contains the module test test
  bed. To run individual module tests, specify the class names as
  command line parameters.

<h4>test/com/ComMobTestAAF/ModuleTests</h4>

Contains the individual module tests. This contains usage code of
  the methods in each Com interface.<br> In general, the examples
  directory contains more useful example usage, but if a method is not
  used in any example, the module test provides at least a minimal
  usage example.

<h4>test/com/CreateSequence</h4>
Contains tests of the sequence and composition mob
<h4>test/com/EssenceAccess</h4>

Contains test of the EssenceAccess interfaces Utilities aafOMF
conversion utility.

<HR>

<P> I get the following error when I try to run one of the test
  programs. What's wrong ?</P>

Attempting to load the AAF dll...FAILED! RESULT = -2147024770 (0x8007007e) The 
specified module could not be found. The directory containing "aafdll" is not 
in your PATH (on Unix LD_LIBRARY_PATH). 

<P> When I run the module tests AAFEssenceAccess fails. What's wrong ?</p>

The EssenceAccess test is looking for the file Laser.wav in the
  current directory. Either run the module tests from the
  AAFWinSDK/Test/com/ComModTestAAF directory or copy
  AAFWinSDK/Test/com/ComModTestAAF/Laser.wav to your current
  directory.

<P> I've copied Laser.wav to my current directory and the test still
  fails. What's going on ?</P>

Make sure you're not using a Macintosh version of Laser.wav on another
platform.  macintosh binary files are encoded for CVS.

<HR>

<!--

What are the plans for implementation of content protection within AAF ?


Where is the description of what AAF and MXF are as a bitstream or file ?

What is the bitstream syntax?

[TBS - supply references to the SMPTE documents]

Are AAF and MXF just wrappers around the compressed audio and video
content with provision for storing metadata ?

Is the only access to the content through the API?

Is all the metadata in KLV?

Does AAF define dictionaries for the KLV then?

Is there other ancillary data embedded in the bitstream?

Are the video and audio compressed to MPEG (or other) standards and
the bits embedded unchanged in the AAF or are they modified but
reconstituted upon access?

In AAF the bit streams are unmodified.

What about MPEG System streams?

Where are the AAF Golden files ?

Where are Josh Goldman's 5 presidents examples from SantaFe?

They are at aafassociation.org

What are some real KLV codes ?

Who maintains them?

 -->

<HR>

<P> Are there any File icons for AAF files - eg Mac BNDL and Win32
  equivalent ?</P>

No, not at present. 

<HR>

<!--

What's the deal with this 1K padding at the head of JFIF files ?

What sort of standard do they conform to in this state - is there a
Motion JPEG standard ?

-->

<P> What is AAFPersonnelExtension.DLL ?</P>

This dll is part of an example that shows how to extend AAF. AAF is
extended using plugins. The example extension includes "personnel"
meta-data, AAFPersonnelExtension.DLL is the example extension plugin.

<HR>

<P> Why doesn't the OMF to AAF converter build on Linux ? </p>

A version of the OMF library needs to be built for Linux. 

<HR>

<P> Why does it say "This project has no CVS history." for AAF. I
  thought that you checked in all of the RC1 files with their revision
  history ?</P>

The AAF CVS repository on SourceForge does indeed contain a revision
history for each file. The message is referring to the file
/cvsroot/aaf/CVSROOT/history which, if present, records a history of
repository activity (as opposed to activity relating to a particular
file within the repository). It appears that repository history is
disabled for most if not all projects on SourceForge since many
display the message "This project has no CVS history."

<HR>

<P> Are the OMF libraries incorporated in to <b>aafdll</b> or is it an
  optional plugin ?</P>

Neither, the OMFI library is only used by the AAf/OMF converter utility. 

<P> What's the absolute minumum what the user has to have in order to
  build/run an application that uses AAF ?</P>

Look at the makefile and or projects for one of the example
programs. I've a feeling that this question wouldn't be asked if
ready-built SDKs were made available on SourceForge. To see what went
onto previous SDKs look at the installers for older versions of the
SDK which should still be availabel on the AAF Associatiuon ftp site.

<P> How did you import the binary files for the Mac files to CVS with resource 
  forks ?</P>

<p>How are they encoded ?</p>

I created the entire AAF CVS tree for all platforms on Linux using
files exported from our ClearCase configuration management system (the
export process ran on SGI Irix). ClearCase (plus Xinet and some Avid
extensions) stores, in addition to the data fork, the resource fork
and finder information for Macintosh files.  Macintosh CVS clients all
recognize some form of encoding for binary files they check in or out
of CVS. Since most Macintosh CVS clients seemed to support
AppleSingle, that's the way I encodeed the files (on Unix using the
karc utility from Xinet) before adding them to CVS.

<P> Did you get MacCVS to work for SSH ?</P>

<!--

No. I've successfully used anonymous CVS access from Windows, Linux
and Macintosh but I've only used ssh access from Linux.

 -->

There is a workable solution using MacCVSpro and MacSSH set for port
forwarding see our <a
href="http://aaf.sourceforge.net/sshMacOS.html">CVS/SSH Mac</a> page.

<P> I'm having problems with text file line endings using MacCVS on
  OSX, what's going on ?</P>

OSX is a Unix-like operating system and expects Unix style line
endings. MacCVS is a client for MacOS and obeys the Macintosh line
ending convention when checking text files out from CVS. When checking
out files to OSX try the "cvs(1)" command line program.

<P> AAF won't build on Red Hat Linux version 7.0 (gcc 2.1.92), I get errors in 
  /usr/include/_G_config.h, what's going on ?</P>

<p>What versions of Linux and gcc does AAF build with ?</p>

<a name="#glib_problems"></a>We have previously (for RC1) tried Red
Hat Linux 6.0 and 6.1. I recently (post RC1) tried version 7.1 (gcc
2.96) There's a bug in in _G_config.h which does #include(a standard
header) to get a definition of __mbstate_t (an implementation specific
typedef).<br> Implementation specific typedefs should be obtained from
implementation specific header files not from public header files like
wchar.h.<br> Because there is ss-impl/ref/h/wchar.h the definition of
__mbstate_t is not found.<br> I have worked around this problem by
changing the makefiles and the #include directive for the structured
storage reference implementation - these changes are checked in (post
RC1) to CVS on SourceForge.

<p> When I try to build AAF on Linux
I get compilation errors in ref/impl/src/OM/OMUtilities.cpp
saying that uuid/uuid.h can't be found. How can I fix this ?
</p>

Make sure the uuid library is installed.  For rpm based distributions the
uuid library is in the e2fsprogs-devel package:
<pre>
$ rpm -q e2fsprogs-devel
e2fsprogs-devel-1.27-9
</pre>
For deb based ditributions such as Ubuntu:
<pre>
$ dpkg -p uuid-dev
</pre>

The Object Manager uses uuid_generate() from this package to create
uuids.  Alternativley you can build the Object Manger to use a
built-in uuid generator (define OM_USE_OM_CREATEUUID).

<hr>

<p>Was dodo written specifically for AAF or is it in-house an Avid tool ?</p>

Specifically for AAF. It was originally intended to be thrown away,
hence the name, the "dodo" is an extinct flightless bird.

<P> How would you describe "dodo" ?</P>

It' a macro processor. 

<p> What is/was the the <i>intended</i> way to EXTEND an interface using dodo ?
<br>
(and I mean that in the proper legal  COM sense of course)
</p>

Before answering the dodo question let's make sure we have the terminology and
rules straight.
<br>

You cannot extend individual interfaces you can however extend the API
by adding new interfaces. You may not remove or change existing
interfaces, this is in order to maintain compatibility of older
applications with newer libraries. When a new interface is added it
gets a new IID, only the new applications know that they can
successfully QueryInterface() for that new IID.

<p>Do new interfaces respond to both the new and the old UUIDs</p>

No. It would break binary compatibility to get the new interface in response to
a QI() for the old one.

<br>

Typically new interfaces are interfaces to new functionality, However,
there's a common special case of adding a new interface to existing
functionality.

<br>
Let's say I have (in no particular syntax)<br>
<br>
interface foo {<br>
  method a();<br>
  method b();<br>
  .. lots of methods ...<br>
  method p();<br>
  method q();<br>
}<br>
<br>
But I wish there was also an r() method. I could address this by adding the
following new interface<br>
<br>
interface foo1 {<br>
  method r(); // only<br>
}<br>
<br>
foo1 has a different IID than foo.<br>
<br>
However new clients would have to use both foo and foo1. Another way I could
address this would be to add the following new interface
<br>
interface fooEx {<br>
  method a();<br>
  method b();<br>
  .. lots of methods ...<br>
  method p();<br>
  method q();<br>
  method r();<br>
}<br>
<br>
fooEx has the same methods as foo except with the addition of r(). This way new
clients can ignore foo and only use fooEx. Note that, just as for foo1, fooEx
has a different IID than foo. For the convenience of new clients we've repeated
all the methods of foo (at least the ones we didn't want to "change") in fooEx.
<br>
Now since foo and fooEx are very similar interfaces we can (and probably should
in AAF) have foo and fooEx share the same implementation. Note that this is an
issue for implementors, not for clients, and is a different concept than having
"the new interface respond to both the new and the old UUIDs".
<br>
For an example of how this is done in AAF see "interface
IAAFTypeDefVariableArray" and "interface IAAFTypeDefVariableArrayEx".
<br>
The naming convention seems to be foo fooEx fooEx1 ...

<p>is dodo capable of generating interfaces that share common
implementation ?</p>

You make fooEx.dod by copying foo.dod, giving it a new IID, and
modifying it. If you want to share implementations, dodo knows, if you
tell it, how to have an implementation support more than one
interface, again see IAAFTypeDefVariableArray and
IAAFTypeDefVariableArrayEx.

<br>
dodo also knows how to have the same interface supported by more that one
implementation, see IAAFEndian.

<hr>

<p>Why does the AAF Toolkit leak objects ?</p>

Given the following two code fragments - W and R.
<br>
First consider the case in which R is executed after W in the same
program. The object referenced by q leaks because it is not released
(R4). In this case, most leak detection tools will report a problem in
the object creation code inside the AAF Toolkit, with W2 on the call
stack, as this is where the leaking object was created. Without too much
trouble one can trace from W2 to the cause of the leak - the Get() at R2
without a corresponding Release().
<br>
Now consider the case in which after W the objects are saved to an AAF
file, the file is closed and the program exits. Some time later, most
likely on a different computer, the file is then opened and the
objects in it are restored by the toolkit. Then the code fragment R is
executed. There's still a leak caused by the missing Release at R4,
however most leak detection tools will report a problem in the object
restore code inside the AAF Toolkit (this is, after all, the place at
which the leaking object was created). It is not immediately obvious
that the actual cause of the leak is the Get() at R2 without a
corresponding Release().
<br>
<br>
<pre>
Code W

  IAAFSomething* p = 0;            // 1

  d->CreateInstance(..., &amp;p);      // 2

  e->Set(p);                       // 3

  p->Release();                    // 4


Code R

  IAAFSomething* q = 0;            // 1

  e->Get(&amp;q);                      // 2

  ... Use q ...                    // 3

  // q->Release();                 // 4
</pre>
<br>
<br>
The lesson here is that if your leak detection tool reports leaking
objects and those objects were created in the object restore code of the
AAF Toolkit then you should look for missing Release()s in your AAF
Toolkit client code.
<br>
The AAF Toolkit is by no-means perfect and from time-to-time bugs are
introduced. In general these are fixed promptly. Also, tools such as
BoundsChecker, valgrind and the Microsoft CRT heap debugging routines
are run fairly regularly on the AAF toolkit. However, in our experience,
most reported AAF toolkit leaks turn out to be caused by missing
Release()s in the client code.
<br>
<hr>

<P> What's the deal with Unicode and wchar_t ?</P>

<p>What are the portability issues ?</p>

The ANSI/ISO C way to support Unicode is via wchar_t (from
<b>&lt;stddef.h</b>&gt;), nearly all compilers support wchar_t. More
problematic are the wcs functions (from
<b>&lt;wchar.h&gt;</b>) since this was a late addition to ISO some
compilers may not support all the wcs function or they may have them
in different header files.<br> The AAF policy is that all
strings/characters in memory and across the API are wchar_t (the size
of which varies across platforms) and all strings/characters in AAF
files are 2-byte unicode. Any transformation to from the in memory
wchar_t to the 2-byte external form is done transparently to the API
client.

<p>What are the UNICODE and _UNICODE preprocessor symbols for ? </p>

<p>What's the difference ?</p>

These symbols are Microsoft specific (you'll encounter them on
non-Microsoft platforms because AAF uses Microsoft Structured storage
on all platforms). Defining them alters the prototypes (at compile
time) of functions in a couple of APIs to point to the Unicode
versions of various functions. The symbol UNICODE is for the Win32 API
and the symbol _UNICODE is for the the C run time API. The symbols
work something like this ... Given (say in the W32) API void
Foo(TCHAR* bar); with UNICODE not defined this maps to void Foo(char*
bar); with UNICODE defined this maps to void FooW(wchar_t* bar); Of
course this is confusing and pollutes the name space. For example try
debugging ImplAAFEssenceAccess and you see that the CreateFile member
ends up as CreateFileW, bah !  <hr>

<p> Is there a way to receive a more meaningful HRESULT when
  attempting to erroneously create an aaf file that already exists
  ?</p>

If I try this, the HRESULT I get from <b>AAFFileOpenNewModify</b>() is
AAFRESULT_ASSERTION_VIOLATION.<br> However the call to
<b>AAFFileOpenNewModify</b>() resulted in a call to StgCreateDocfile()
which did return a meaningful HRESULT (0x80030050, already exists)
indicating that the file already exists.Unfortunately there is
currently no way to receive a more meaningful HRESULT when attempting
to erroneously create an .AAF file that already exists.<br>

We planned to provide complete error handling in the Object Manager
but that work has not yet been done. This work was deferred to
concentrate on work items of higher priority.Currently the HRESULT
returned by StgCreateDocfile() is lost.  I suggest the following
<i>workaround</i> - Use the host file system [ansi - <b>fopen</b>(),
W32 - <b>CreateFile</b>() etc.] to check that the file does not
already exist prior to calling <b>AAFFileOpenNewModify</b>()<br> If
you have a GUI you probably want to report the error that the file
already exists when the user _chooses_ the name of the file to create
i.e. before calling
<b>AAFFileOpenNewModify</b>(). Alternatively you could try calling the
W32 API function GetLastError() Other workarounds involving the use of
<b>AAFCreateAAFFileOnRawStorage</b>() [available in RC1] may be
possible. <br> Note that the goal is for AAF to support multiple
external representations. In addition to structured storage binary
files, support for XML (text) and SMPTE KLV (binary) encodings is
possible.<br> This means that calls to <b>AFFileOpenNewModify</b>()
don't always result in a call to <b>StgCreateDocfile</b>(). For each
external representation the function called by the Object Manager to
open/create the file is different and may not even return an HRESULT
[e.g. fopen()]<br> Any error handling scheme that is eventually
implemented in the Object Manager needs to take the support for
multiple external representations into account while still preserving
any HRESULT that may be available.

<hr>

<p>When I try to build the AAF reference implementation on Windows 98
  everything works fine until I reach the <b>win32aafsdk.mak</b>
  step. Exactly one command seems to be echoed, but doesn't get
  executed, then everything hangs. <br> After a fresh checkout out
  that one command is "md" to make a directory. If I make the
  directories by hand the command that hangs is the first "copy". If I
  do the first copy by hand then it hangs on the next copy command and
  so on.  When a hang occurs I can't stop the build with the button in
  the tool bar. I have to kill "vcspawn" with the task manager. After
  doing this a couple of times the system becomes unusable and I can't
  shut it down cleanly. What's going wrong ?</p>

Disable all anti-virus software. There are two different win api calls
for spawning, and one of them gets intercepted by Norton Anitvirus
(and I've also seen the same report for MacAfee). This problem was
confirmed with Windows 98 and Norton Anti-Virus.

<hr>

<p>How do I get Visual Studio to prompt me with AAF class and
  interface information ? </p>

In order to use the AAF class and interface information in Visual
Studio (which is not automatically built in the project files on
SourceForge).<br> You will need to enable the generation of .SBR files
when the AAF project is built, then concatenate all these files
together using the <b>bscmake</b> tool from a command line<font
face="Verdana, Arial, Helvetica, sans-serif">.</font><br>

<br>

With the top level AAFWinSDK workspace open, select
Project-&gt;Settings...<br> Select the C/C++ tab and highlight the
projects you want to generate Browse info for on the left (most of the
ones that start AAF...).<br> Then check the <b>Generate Browse info
box</b> and hit OK.<br> The .SBR files during the build you can be
combined with the <b>bscmake</b> command.<br>

From the command line call bscmake with list of all the sbr files.In a
<b>bash</b> shell this is something like:<br>

<font face="Courier New, Courier, mono"><br>
cd AAF/AAFWinSDK/ref-impl<br>
bscmake /o mydata.bsc */Debug/*.sbr</font><br>
<br>

Then open the mydata.bsc file in visual studio. By highlighting a
member function you will be now have the option to see it's parameters
or jump to the definition.<br> Be careful not to check these modified
project files back in to sourceforge.

<hr>

<p>I'm having problems getting CVS to work, is there any way to view
  individual source files ?</p>

Yes, the <a href="http://aaf.cvs.sourceforge.net/aaf/">CVS 
browse interface</a> on SourceForge allows you to download individual files as 
well as viewing the differences between versions. 

<hr>

<p>The C++ Standard Template Library (STL) doesn't seem to be used anywhere in 
  the current AAF implementation.<br>
  Is this a deliberate policy? if so, why? </p>

It is a deliberate policy. It was done for portability
(i.e. portability between different implementations) and to eliminate
an extra dependency. At the time we started AAF development (early
1998) the STL implementations in our first three compilers (VC++ 5.0,
or was it 4.0?, CodeWarrior 3, and the SGI C++ compiler [GNU C++ was
not on the list at that time]) were very inconsistent and patchy. The
STL implementations have improved since then, I'm using the STL on
another project where portability is less of a concern, but I still
have to refer frequently to "Effective STL" by Scott Meyers. I'd
recommend sticking to this policy for the AAF reference
implementation. <br> <br> The only appearence of &lt;iostream&gt; is
in the Object Manager code for debug, and it's very easy to turn it
off (see <a href="#OMdebug">OMdebug</a> above ).
<br>

<hr>

<p>I ran one of the example programs that are distributed with the AAF
  toolkit and created an example AAF file.<br> When I try to import
  the file into &lt;product x&gt; it doesn't work, why not ?</p>

While those example programs do create AAF files they certainly do not
create AAF files with the correct contents such that they can
successfully be imported by &lt;product x&gt;. An AAF file can be
thought of as a container. Having the correct container is is not
sufficient, one must also have the correct contents for the file to be
acceptable to the consumer. The AAF Association is aware of this issue
and is working on a solution variously known as "Templates" or
"Operational Patterns".

<hr>

<p>
  <a href="http://validator.w3.org/check?uri=referer">
    <img border="0"
         src="http://www.w3.org/Icons/valid-html401"
         alt="Valid HTML 4.01!"
         height="31"
         width="88">
  </a>
</p>

</BODY>
</HTML>
 
